home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 1.iso / ARGONET / PD / WWW / LINKCHECK.ZIP / !LinkCheck / !Help < prev    next >
Text File  |  1998-02-09  |  14KB  |  320 lines
  1.       |  _  |  __ |  __   !LinkCheck 1.13 09Feb98
  2.   |_| | |_) | |_  | |_    
  3.   | | | | \ | |__ | |     Checks a local directory
  4.  —————+—————+—————+—————  containing a web-site to
  5.    /  | /¯\ |  // |  \    verify the existence of
  6.    \  | |¯| | //  |  /    all files referenced in
  7.  —————+—————+//———+—————  hypertext links and image
  8.    \\ |     //    |       tags, eg: <A HREF=...>,
  9.     \\|    //     |       <AREA HREF=...>, <BODY BACKGROUND=...>,
  10.  ————\\———//+—————+—————  <IMG SRC=...>, <IMG USEMAP=..>, <FORM ACTION=..>,
  11.       \\ // |     |       <INPUT NAME="linkto" VALUE=..>, & <FRAME SRC=..>;
  12.       |\×/  |     |       tabling a “connectivity” map.
  13.                           
  14.  Operating Instructions   (please read!  ;-)
  15.  ======================   
  16.  
  17.  To achieve full functionality, LinkCheck needs three options files:
  18.  a BASIC file called !Choices, a text file called !SrcDiry, and a
  19.  text file called !BaseURLs.
  20.  A default !Choices file is supplied, and LinkCheck WILL run with
  21.  NONE of these present, so you may well be able to skip setting these up,
  22.  and get straight on with using this application “as is”.
  23.  
  24.  But you are recommended to refer to the descriptions of these, which
  25.  are at the end of these instructions... at least eventually!
  26.  
  27.  Running/installing
  28.  ------------------
  29.  To Run !LinkCheck, double-click on its icon, and it will install itself
  30.  on the icon-bar.
  31.  
  32.  The icon-bar menu
  33.  -----------------
  34.  If you click Menu on the icon-bar icon, you will get a standard menu:
  35.  the first and last items are the usual “Info” and “Quit” items.
  36.  
  37.  Clicking on the second item “Help...” brings up this instructions file.
  38.  
  39.  The third item “Options =>” leads to a window showing the current
  40.  settings for maximum numbers and sizes of files that can be processed,
  41.  and of any special requirements to check FORMs-submissions against.
  42.  If these need amending, see the section “!Choices/Options” at the end
  43.  of these instructions.
  44.  
  45.  If a valid !SrcDiry file is present, containing the full path name of
  46.  a directory containing a site (or an HTML file in it):  clicking on the
  47.  fourth option (the leafname of the above path name) will analyse it.
  48.  Otherwise it is the greyed-out word “!SrcDiry”:  to set this up, see the
  49.  “!SrcDiry” section at the end of these instructions.
  50.  
  51.  The icon-bar icon
  52.  -----------------
  53.  If you click (Select) on the icon-bar icon, a “drop target” window 
  54.  appears.
  55.  
  56.  Later on in a session, if you click Adjust on the icon-bar icon,
  57.  it will offer to re-analyse the last thing it did; 
  58.  this is intended for when you’ve done one run, corrected some errors,
  59.  and want to re-run to check that the errors have now been removed,
  60.  but should NOT be used if you have added any NEW files to the site.
  61.  
  62.  Now to actually get it to do something:
  63.  ======================================
  64.  There are three ways of starting up:
  65.  
  66.  [1]
  67.  Drag EITHER the directory icon of the directory containing your site,
  68.  OR an HTML file within that directory;  on to any of:
  69.  (a) the icon-bar icon,  or
  70.  (b) the “drop target” window if it is showing,  or
  71.  (c) (later on in a session) any LinkCheck window that’s open.
  72.  
  73.  [2]
  74.  To re-do a previously-analysed directory, Adjust on the icon-bar icon.
  75.  
  76.  [3]
  77.  To analyse the directory specified inside !SrcDiry (if that has been
  78.  set up), click Menu on the icon-bar icon, and select the fourth item.
  79.  
  80.  
  81.  A window will appear saying “Cataloging...” (and an hourglass until
  82.  it has finished).
  83.  This happens regardless of whether it was a file or a directory that
  84.  was dragged in.
  85.  If the site directory contains sub-directories, these will be indexed
  86.  recursively.
  87.  
  88.  That window then gets replaced by the
  89.  
  90.  LinkCheck Control window
  91.  ------------------------
  92.  The first three items show:
  93.     the path-name of the file or directory,
  94.     the number of HTML (and .map) files, and
  95.     the total number of files in the directory.
  96.  
  97.  There are then five tickable option buttons:
  98.  [ ] Do this page only :  only available if a FILE was dragged in.
  99.  [ ] Follow #fragments :  eg as in HREF=page2.html#para3:  this adds to
  100.                           the processing time, so should be left unticked
  101.                           the first time you check a potentially error-
  102.                           ridden directory, to reduce output ;-)
  103.  [ ] Check image dimns :  both for their presence, and being correct:
  104.                           there is no significant increase in processing
  105.                           time, but this can generate a lot of output if
  106.                           your IMG WIDTH/HEIGHT attributes are missing!
  107.  [ ] Verbose reporting :  in the Report file generated:  this will name
  108.                           every HTML/.map file that it processes even if
  109.                           error-free; and also notes any “off-site” URLS
  110.                           so don’t turn it on for pages full of Links!
  111.  [ ] Ignore fName case :  allows for “name.ext” in the HTML, but
  112.                           “NAME/EXT” as the local filename (as perhaps
  113.                           a site directory in a DOS partition).
  114.  
  115.  The [Catalog...] button brings up a menu allowing you to View, Print,
  116.  or Save the catalogue that has just been indexed.
  117.  You will need this index to interpret the “Matrix” later;  but there’s
  118.  no need to get the index out immediately:
  119.  If you JUST want this catalogue (do not intend to do a full analysis),
  120.  now’s the time to do it;  but if you DO intend to carry on with the full
  121.  analysis, the opportunity to access the Catalog will be repeated later.
  122.  
  123.  The [Cancel] button does just that.
  124.  
  125.  Click on [Analyse] to start the process;  this produces the
  126.  
  127.  LinkCheck Analysis window
  128.  -------------------------
  129.  The first three long display lines show:
  130.     the name of the file currently being processed;
  131.     the tag being commented upon (if any) and its line number;
  132.     any comment (in blue) or error (in red) it has found.
  133.  
  134.  At bottom left are running counts of the number of files processed, and
  135.  the accumulative number of errors found (“comments” are not counted).
  136.  
  137.  The hourglass is displayed during the scanning process.
  138.  
  139.  Although there is no “Stop” button, if you realise you’ve started
  140.  something you didn’t intend to, you can interrupt the process by
  141.  pressing the [Esc] key.  Obviously, any Report file that was being
  142.  generated will be incomplete, and no Matrix file is generated.
  143.  
  144.  When it’s finally finished, it will summarise any instances of
  145.  pages leading nowhere, unreferenced files, and failed links;
  146.  Note that a a reference to "/cgi-bin/whatever" will usually generate
  147.  a "failed link" error (but "http://www.domain/cgi-bin/..." wouldn't).
  148.  
  149.  Then four more buttons appear:
  150.  [Close] [View...] [Print..] [Save...]
  151.  
  152.  Clicking on [Close] merely closes the window (I bet you guessed that ;-)
  153.  
  154.  Inspecting/saving the results
  155.  -----------------------------
  156.  Clicking on any of the other three brings up a three-item menu:
  157.      Catalog
  158.      Report
  159.      Matrix
  160.  
  161.  “Catalog” refers to a list of all the files in the site directory;
  162.            it also shows the “file numbers” which are VITAL for
  163.            interpreting the “Matrix” output!
  164.  
  165.  “Report”  refers to the report of all errors found (and possibly
  166.            comments too, if Verbose reporting was selected).
  167.  
  168.  “Matrix”  is the “connectivity map” showing all links between all files,
  169.            highlighting any unconnected files, and counting failed links.
  170.  
  171.  When you select a file, what happens depends on the previous button:
  172.  
  173.  [View...] just throws the relevant file into your configured text editor;
  174.  
  175.  [Print..] simply bangs ASCII text out of the parallel printer port
  176.            (none of this fancy PrinterDriver_InscrutableOp stuff  ;-)
  177.            however, it will turn condensed on if printing a wide matrix.
  178.  
  179.  [Save...] produces a “Save as” dialogue box, which is not quite standard
  180.            in that
  181.            (a) it’s not transient, so doesn’t disappear when you go to 
  182.            open a directory to drag the text icon to;  and
  183.            (b) it doesn’t have one of those [OK] buttons which merely
  184.            generate an error telling you you’re an idiot to click on it!
  185.  
  186.           So you must drag the textfile to a destination directory
  187.            (you may edit the suggested leafname first if you want to).
  188.  
  189.            However, saving is actually done by using *Copy, so it
  190.            doesn’t implement application-to-application transfer.
  191.  
  192.  Note that all three of the above files can always be found by
  193.  SHIFT-double-clicking on the !LinkCheck icon to open its directory.
  194.  
  195.  The connectivity Matrix
  196.  -----------------------
  197.  [If only a single page was analysed, this report summmarises all the
  198.  links from that page, but there is no “matrix” as such;  the following
  199.  description only applies when a whole site directory has been analysed]
  200.  
  201.  If there are n HTML files, and N files in total:
  202.  
  203.  The top line says “\Fr” (meaning “from”), followed by the numbers
  204.  1 to n, followed by “To”.
  205.  
  206.  The left-hand column is headed “To\”, followed by the numbers 1 to N
  207.  (with a gap after the first n, to separate HTML files from “others”).
  208.  
  209.  Note that nowhere is there any mention of actual fileNAMES;  you must
  210.  refer to the “Catalog” to decode the numbers  (basically, there just
  211.  isn’t room to squeeze full names into a potentially very wide table).
  212.  
  213.  The number in each cell of the table is the number of times there is
  214.  a reference in the file with that column number to the file with that
  215.  row number.
  216.  
  217.  The (n+1)th column contains the totals for each row, ie the number of
  218.  times the file in that row has had a reference to it.
  219.  If a total of zero occurs, it will be asterisked, because it means that 
  220.  that page or file is never accessed or referenced.
  221.  
  222.  The (N+1)th row contains the totals for each column, ie the number of
  223.  references from the file in that column  (there are also subtotals
  224.  after the nth file, which should include all on-site hypertext links,
  225.  but exclude references to IMaGe SouRCes)
  226.  
  227.  Again, any totals of zero are highlighted, because that means that the
  228.  page doesn’t lead anywhere (not even back to the index page).
  229.  
  230.  Below that there is a row labelled “Bad” enumerating the number of
  231.  failed links from that page:  these should all be zero!
  232.  
  233.  In the penultimate line, the “column heading” is repeated.
  234.  
  235.  Finally, a summary of pages leading nowhere, unreferenced files,
  236.  and failed links.
  237.  
  238.  If it is a framed site, “failed links” includes instances where an
  239.  anchor has a TARGET= attribute, but the frame name could note be found
  240.  in a <FRAME> tag;  this can occur erroneously if the frame-defining page
  241.  is not “index”, and does not get analysed until after the page containing
  242.  the TARGET.
  243.  
  244.  Also in framed sites, the “index” page probably has no references to it:
  245.  this would be normal, but reported by !LinkCheck.
  246.  
  247.  Setting up the three Options Files
  248.  --------------------==============
  249.  Any or all of these can be missing, and the program will still work; but
  250.  setting them up will enable you to get the most out of the application.
  251.  
  252.  File “!Choices”
  253.  --------------
  254.  If this is absent, internal default options will be used.
  255.  
  256.  If present, it is a short BASIC LIBRARY procedure which initialises
  257.  some parameters;  it is not necessary for all parameters to be set.
  258.  
  259.  Once LinkCheck is running, you can read the settings by clicking Menu
  260.  on the icon-bar icon, and moving across the item “Options =>”.
  261.  
  262.  If you want to edit it:  this is a BASIC file, so you need to
  263.  SHIFT-double-click on it to put it into an editor.
  264.  
  265.  The first three are used to determine the size of arrays inside:
  266.  “max1%=” sets a maximum to the number of HTML and “.map” files, and
  267.  “max2%=” sets the maximum total number of files to be expected:
  268.  the default values for these are 52 and 255 respectively, and I do
  269.  not recommend that max1% be increased beyond about 85;
  270.  “maxF%=” sets a limit to the largest file-size (in bytes) of an HTML 
  271.  or “.map” file that can be loaded and analysed; the default is 32K.
  272.  
  273.  If your site needs these values increasing, then you should do so;
  274.  but if the existing values are large enough, increasing them will
  275.  merely waste memory!
  276.  
  277.  The next three are used for parameters for server-side reply form
  278.  processing;  you can ignore them if they are not relevant to you.
  279.  
  280.  “formMethod$=” and “formAction$=” specify “trigger” values for the
  281.  METHOD= and ACTION= attributes within a <FORM ...> tag:  these are
  282.  set to the values required to access the server-side form-decoder
  283.  (which for Argonet are "GET" and "http://www.argonet.co.uk/cgi-bin/mail"
  284.  respectively), and if present, subsequent <INPUT ...> tags are searched
  285.  for a NAME= attribute whose value matches that specified by the last
  286.  parameter “formName$=” (whose value for Argonet is "linkto").
  287.  (If you haven’t understood the above technobabble, don’t worry :-)
  288.  
  289.  
  290.  File “!SrcDiry”
  291.  --------------
  292.  If you have one particular web-site directory that you will want to
  293.  check regularly (eg the local copy of your own site, as you update it),
  294.  its pathname should be in this text-file.
  295.  
  296.  An empty !SrcDiry file is supplied;  double-click on it to load it
  297.  into your text editor.  You could then type in the full pathname of
  298.  the directory;  but you can simplify this (in !Edit) by SHIFT-dragging
  299.  the directory icon on to the page.
  300.  
  301.  
  302.  File “!BaseURLs”
  303.  --------------
  304.  You should also create a textfile inside !LinkCheck called “!BaseURLs”
  305.  containing the base URL(s) of your “real” site (up to three of them).
  306.  
  307.  (This is so that the program can look at full absolute URLs and be
  308.  able to “know” whether they refer to your site, in which case it will
  309.  expect to be able to find the leafname locally; or whether it refers
  310.  to a different site altogether, so there’s no point in looking!)
  311.  
  312.  If not required, this file may be absent or empty.
  313.  
  314.  
  315.  
  316.                                               John Alldred 09Feb98
  317.                                               john@protovale.co.uk
  318.                                   http://www.protovale.co.uk/john/
  319.                 http://www.argonet.co.uk/users/protovale/john.html
  320.